---
title: Media
description: Embed medias like videos or tweets into your document.
docs:
  - route: /docs/components/image-element
    title: Image Element
  - route: /docs/components/media-embed-element
    title: Media Embed Element
  - route: /docs/components/media-popover
    title: Media Popover
  - route: /docs/components/media-toolbar-button
    title: Media Toolbar Button
---

<ComponentPreview name="playground-demo" id="media" />

<PackageInfo>

## Features

- Allows insertion of embeddable media: images, videos, and tweets.
- Supports multiple media providers: video, youtube, vimeo, dailymotion, youku, coub, twitter.
- Editable captions.
- Resizable.
- Use [Plate Cloud](/docs/cloud) for easy cloud uploads and server-side image resizing.

</PackageInfo>

## Installation

```bash
npm install @udecode/plate-media
```

## Usage

```tsx
import { CaptionPlugin } from '@udecode/plate-caption/react';
import {
  ImagePlugin,
  MediaEmbedPlugin,
} from '@udecode/plate-media/react';
import { SelectOnBackspacePlugin } from '@udecode/plate-select';

const plugins = [
  // ...otherPlugins,
  CaptionPlugin.configure({
    options: { plugins: [ImagePlugin, MediaEmbedPlugin] },
  }),
  ImagePlugin,
  MediaEmbedPlugin,
  SelectOnBackspacePlugin.configure({
    options: {
      query: {
        allow: [ImagePlugin.key, MediaEmbedPlugin.key],
      },
    },
  }),
];
```

## Plugins

### ImagePlugin

<APIOptions>

Extends `MediaPluginOptions`.

<APIItem name="uploadImage" type="(dataUrl: string | ArrayBuffer) => Promise<string | ArrayBuffer> | string | ArrayBuffer" optional>

An optional method that will upload the image to a server. The method receives the base64 dataUrl of the uploaded image, and should return the URL of the uploaded image.

</APIItem>
<APIItem name="disableUploadInsert" type="boolean" optional>
Disables file upload on data insertion if set to true.
</APIItem>
<APIItem name="disableEmbedInsert" type="boolean" optional>
Disables URL embed on data insertion if set to true.
</APIItem>
</APIOptions>

### MediaEmbedPlugin

Options extends `MediaPluginOptions`.

## API Media

### insertMedia

Inserts media (image or media embed) into the editor. The type of media to insert is determined by the `type` parameter.

<APIParameters>
<APIItem name="editor" type="PlateEditor">
The editor instance.
</APIItem>
<APIItem name="options" type="InsertMediaOptions" optional>
<APISubList>
<APISubListItem
  parent="options"
  name="getUrl"
  type="function"
  optional
>
A function that returns a promise resolving to the URL of the media to
be inserted. If not provided, a prompt will be displayed to enter the
URL.
</APISubListItem>
<APISubListItem parent="options" name="type" type="string" optional>
The type of media to insert. Defaults to the editor's image element
type.

- **Default:** `editor.getType(ImagePlugin)`

</APISubListItem>
</APISubList>

</APIItem>
</APIParameters>

### parseMediaUrl

Parses a media URL and returns the data associated with it based on the configured rules of the media plugin.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="options" type="object">
    <APISubList>
      <APISubListItem parent="options" name="pluginKey" type="string">
        The key of the media plugin.
      </APISubListItem>
      <APISubListItem parent="options" name="url" type="string" optional>
        The URL of the media to be parsed.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIParameters>

### submitFloatingMedia

Submits the floating media element by setting its URL and performing necessary transformations.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="options" type="object">
    <APISubList>
      <APISubListItem parent="options" name="element" type="TMediaElement">
        The floating media element to be submitted.
      </APISubListItem>
      <APISubListItem parent="options" name="pluginKey" type="string" optional>
        The key of the media plugin.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIParameters>

### MediaPluginOptions

Common attributes shared by image and media embed plugins.

<APIAttributes>
  <APIItem name="isUrl" type="function" optional>
    A function to check whether a text string is a URL.
  </APIItem>
  <APIItem name="transformUrl" type="function" optional>
    A function to transform the URL.
  </APIItem>
</APIAttributes>

### EmbedUrlData

A type defining the data returned from parsing an embed URL.

<APIAttributes>
  <APIItem name="url" type="string" optional>
    The URL of the embedded content.
  </APIItem>
  <APIItem name="provider" type="string" optional>
    The provider of the embedded content.
  </APIItem>
  <APIItem name="id" type="string" optional>
    The unique ID for the embedded content.
  </APIItem>
  <APIItem name="component" type="React.FC<EmbedUrlData>" optional>
    The component to be rendered for the embedded content.
  </APIItem>
</APIAttributes>

## API Image

### insertImage

Inserts an image element into the editor.

<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="url" type="string | ArrayBuffer">
    The URL or ArrayBuffer of the image.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional>
    Additional options for inserting the image element.
  </APIItem>
  <APISubList>
    <APISubListItem parent="options" name="nextBlock" type="boolean" optional>
      If true, the image will be inserted in the next block.
    </APISubListItem>
  </APISubList>
</APIParameters>

### isImageUrl

Checks if a given URL is a valid image URL.

<APIParameters>
  <APIItem name="url" type="string">
    The URL to check.
  </APIItem>
</APIParameters>

### withImageUpload

Enhances the editor to support pasting images from the clipboard.

<APIParameters>
  <APIItem name="editor" type="E">
    The editor instance.
  </APIItem>
  <APIItem name="plugin" type="PlatePlugin">
    The plate plugin.
  </APIItem>
</APIParameters>

### withImageEmbed

Enhances the editor to automatically insert an image when a URL is pasted.

<APIParameters>
  <APIItem name="editor" type="E">
    The editor instance.
  </APIItem>
  <APIItem name="plugin" type="PlatePlugin">
    The plate plugin.
  </APIItem>
</APIParameters>

## API Media Embed

### insertMediaEmbed

Inserts a media embed element at the current selection.

<APIParameters>
<APIItem name="editor" type="PlateEditor">
The editor instance.
</APIItem>
<APIItem name="options" type="object">
<APISubList>
<APISubListItem parent="options" name="url" type="string" optional>
The URL of the media embed.

- **Default:** `''`

</APISubListItem>
<APISubListItem
  parent="options"
  name="key"
  type="string"
  optional
>
The key of the media embed element.

- **Default:** `MediaEmbedPlugin.key`

</APISubListItem>
</APISubList>

</APIItem>
<APIItem name="insertNodesOptions" type="InsertNodesOptions">
</APIItem>
</APIParameters>

### parseIframeUrl

Parses the URL of an iframe embed.

<APIParameters>
  <APIItem name="url" type="string">
    The URL or embed code of the iframe.
  </APIItem>
</APIParameters>

### parseTwitterUrl

Parses a Twitter URL and extracts the tweet ID.

<APIParameters>
  <APIItem name="url" type="string">
    The Twitter URL.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="EmbedUrlData | undefined">
    An object containing the tweet ID and provider if the parsing is successful.
    Returns undefined if the URL is not valid or does not match any supported
    video providers.
  </APIItem>
</APIReturns>

### parseVideoUrl

Parses a video URL and extracts the video ID and provider-specific embed URL.

<APIParameters>
  <APIItem name="url" type="string">
    The video URL.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="EmbedUrlData | undefined">
    An object containing the video ID and provider if the parsing is successful.
    Returns undefined if the URL is not valid or does not match any supported
    video providers.
  </APIItem>
</APIReturns>

## API Components

### useResizable

A behavior hook for resizable elements.

<APIState>
  <APIItem name="align" type="'left' | 'center' | 'right'">
    The alignment of the content within the resizable element.
  </APIItem>
  <APIItem name="minWidth" type="ResizeLength">
    The minimum width that the resizable element can be adjusted to.
  </APIItem>
  <APIItem name="maxWidth" type="ResizeLength">
    The maximum width that the resizable element can be adjusted to.
  </APIItem>
  <APIItem name="setNodeWidth" type="function">
    A function to set the width of the node, which is used when resizing.
  </APIItem>
  <APIItem name="setWidth" type="function">
    A function to set the width of the resizable element directly.
  </APIItem>
  <APIItem name="width" type="Property.Width<string | number> | undefined">
    The current width of the resizable element. This can be a string (e.g., a
    percentage or 'auto') or a number (representing pixels).
  </APIItem>
</APIState>

<APIReturns>
  <APIItem name="wrapperRef" type="React.RefObject<HTMLDivElement>">
    A React reference to the outermost div wrapping the resizable element.
  </APIItem>
  <APIItem name="wrapperProps" type="React.HTMLAttributes<HTMLDivElement>">
    Props to be spread on the outermost div wrapping the resizable element.
    <APISubList>
      <APISubListItem parent="wrapperProps" name="style" type="CSSProperties">
        CSS styles to be applied to the wrapper div.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="props" type="object">
    Props to be spread on the resizable element.
    <APISubList>
      <APISubListItem parent="props" name="style" type="CSSProperties">
        CSS styles to be applied to the resizable element.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="context" type="object">
    <APISubList>
      <APISubListItem parent="context" name="onResize" type="function">
        A callback function to be called when the resizable element is resized.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useFloatingMediaEditButton

A behavior hook for a floating media edit button.

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem name="onClick" type="function">
        A callback function to handle the button click.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useFloatingMediaUrlInput

A behavior hook for a floating media URL input.

<APIProps>
  <APIItem name="defaultValue" type="string">
    The default value for the URL input field.
  </APIItem>
</APIProps>

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="onChange" type="function">
        A callback function to handle the button click.
      </APISubListItem>
      <APISubListItem parent="props" name="autoFocus" type="boolean">
        If true, the URL input field will be focused on mount.
      </APISubListItem>
      <APISubListItem parent="props" name="defaultValue" type="string">
        The default value for the URL input field.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useImage

A behavior hook for an image element.

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="src" type="string">
        The URL of the media element.
      </APISubListItem>
      <APISubListItem parent="props" name="alt" type="string">
        The caption string for the image.
      </APISubListItem>
      <APISubListItem parent="props" name="draggable" type="boolean">
        Indicates whether the image is draggable.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>

### useMediaState

A state hook for a media element.

<APIParameters>
<APIItem name="options" type="object">
<APISubList>
<APISubListItem parent="options" name="urlParsers" type="EmbedUrlParser[]" optional>
An array of URL parsers to be used to parse the URL of the media element.

- **`EmbedUrlParser`:** `(url: string) => EmbedUrlData | undefined`

</APISubListItem>
</APISubList>
</APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="align" type="string">
    The alignment of the media element.
  </APIItem>
  <APIItem name="focus" type="boolean">
    Whether the media element is currently focused.
  </APIItem>
  <APIItem name="selected" type="boolean">
    Whether the media element is currently selected.
  </APIItem>
  <APIItem name="readOnly" type="boolean">
    Whether the editor is in read-only mode.
  </APIItem>
  <APIItem name="embed" type="EmbedUrlData">
    The parsed embed data of the media element.
  </APIItem>
  <APIItem name="isTweet" type="boolean">
    Whether the media element is a tweet.
  </APIItem>
  <APIItem name="isVideo" type="boolean">
    Whether the media element is a video.
  </APIItem>
  <APIItem name="isYoutube" type="boolean">
    Whether the media element is a YouTube video.
  </APIItem>
</APIReturns>

### useMediaToolbarButton

A behavior hook for a media toolbar button.

<APIParameters>
  <APIItem name="options" type="object">
    <APISubList>
      <APISubListItem parent="options" name="nodeType" type="string" optional>
        The type of the media node to be inserted.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="props" type="object">
    <APISubList>
      <APISubListItem parent="props" name="onClick" type="function">
        A callback function that inserts the media node into the editor and
        focuses the editor.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
